Inside Macintosh: Macintosh Toolbox Essentials
This section describes the Window Manager functions that change a window's display and position in the window list but not its size or location on the desktop. Note that the Window Manager automatically draws all visible windows on the screen.
Your application typically uses only a few of the functions described in this section: DrawGrowIcon (DrawGrowIcon) , SelectWindow (SelectWindow) , ShowWindow (ShowWindow) , and, occasionally, HideWindow (HideWindow) .
pascal void DrawGrowIcon (WindowPtr theWindow);
The DrawGrowIcon function draws a window's size box or, if the window can't be sized, whatever other image is appropriate. You call DrawGrowIcon when drawing the content region of a window that contains a size box.
The exact appearance and location of the image depend on the window type and the window's active or inactive state. The DrawGrowIcon function automatically checks the window's type and state and draws the appropriate image.
In an active document window, DrawGrowIcon draws the grow image in the size box in the lower-right corner of the window's graphics port rectangle, along with the lines delimiting the size box and scroll bar areas. To draw the size box but not the scroll bar outline, set the clipRgn field in the window's graphics port to be a 15-by-15 pixel rectangle in the lower-right corner of the window.
The DrawGrowIcon function doesn't erase the scroll bar areas. If you use DrawGrowIcon to draw the size box and scroll bar outline, therefore, you should erase those areas yourself when the window size changes, even if the window doesn't contain scroll bars.
In an inactive document window, DrawGrowIcon draws the lines delimiting the size box and scroll bar areas and erases the size box.
pascal void SelectWindow (WindowPtr theWindow);
The SelectWindow function removes highlighting from the previously active window, brings the specified window to the front, highlights it, and generates the activate events to deactivate the previously active window and activate the specified window. If the specified window is already active, SelectWindow has no effect.
Even if the specified window is invisible, SelectWindow brings the window to the front, activates the window, and deactivates the previously active window. Note that in this case, no active window is visible on the screen. If you do select an invisible window, be sure to call ShowWindow (ShowWindow) immediately to make the window visible (and accessible to the user).
Call SelectWindow when the user presses the mouse button while the cursor is in the content region of an inactive window.
Makes an invisible window visible.
pascal void ShowWindow (WindowPtr theWindow);
The ShowWindow function makes an invisible window visible. If the specified window is already visible, ShowWindow has no effect. Your application typically creates a new window in an invisible state, performs any necessary setup of the content region, and then calls ShowWindow to make the window visible.
When you display a previously invisible window by calling ShowWindow , the Window Manager draws the window frame and then generates an update event to trigger your application's drawing of the content region.
If the newly visible window is the frontmost window, ShowWindow highlights it if it's not already highlighted and generates an activate event to make it active. The ShowWindow function does not activate a window that is not frontmost on the desktop.
Because ShowWindow does not change the front-to-back ordering of windows, it is not the inverse of HideWindow (HideWindow) . If you make the frontmost window invisible with HideWindow , and HideWindow has activated another window, you must call both ShowWindow and SelectWindow (SelectWindow) to bring the original window back to the front.
pascal void HideWindow (WindowPtr theWindow);
The HideWindow function make a visible window invisible. If you hide the frontmost window, HideWindow removes the highlighting, brings the window behind it to the front, highlights the new frontmost window, and generates the appropriate activate events.
To reverse the actions of HideWindow , you must call both ShowWindow (ShowWindow) , to make the window visible, and SelectWindow (SelectWindow) , to select it.
pascal void ShowHide (WindowPtr theWindow,
Boolean showFlag);
The ShowHide function sets a window's visibility to the status specified by the showFlag parameter. If the value of showFlag is true , ShowHide makes the window visible if it's not already visible and has no effect if it's already visible. If the value of showFlag is false , ShowHide makes the window invisible if it's not already invisible and has no effect if it's already invisible.
The ShowHide function never changes the highlighting or front-to-back ordering of windows and generates no activate events.
Use this function carefully and only in special circumstances where you need more control than that provided by HideWindow (HideWindow) and ShowWindow (ShowWindow) . Do not, for example, use ShowHide to hide the active window without making another window active.
Sets a window's highlighting status.
pascal void HiliteWindow (WindowPtr theWindow,
Boolean fHilite);
The HiliteWindow function sets a window's highlighting status to the specified state. If the value of the fHilite parameter is true , HiliteWindow highlights the specified window; if the specified window is already highlighted, the function has no effect. If the value of fHilite is false , HiliteWindow removes highlighting from the specified window; if the window is not already highlighted, the function has no effect.
Your application doesn't normally need to call HiliteWindow . To make a window active, you can call SelectWindow (SelectWindow) , which handles highlighting for you.
pascal void BringToFront (WindowPtr theWindow);
The BringToFront function puts the specified window at the beginning of the window list and redraws the window in front of all others on the screen. It does not change the window's highlighting or make it active.
Your application does not ordinarily call BringToFront . The user interface guidelines specify that the frontmost window should be the active window. To bring a window to the front and make it active, call the SelectWindow function (SelectWindow) .
Moves one window behind another.
pascal void SendBehind (WindowPtr theWindow,
WindowPtr behindWindow);
The SendBehind function moves the window pointed to by the parameter theWindow behind the window pointed to by the parameter behindWindow . If the move exposes previously obscured windows or parts of windows, SendBehind redraws the frames as necessary and generates the appropriate update events to have any newly exposed content areas redrawn.
If the value of behindWindow is nil , SendBehind sends the window to be moved behind all other windows on the desktop. If the window to be moved is the active window, SendBehind removes its highlighting, highlights the newly exposed frontmost window, and generates the appropriate activate events.
Do not use SendBehind to deactivate a window after you've made a new window active with the SelectWindow function (SelectWindow) . The SelectWindow function automatically deactivates the previously active window.